Swagger 是一款RESTFUL接口的文档在线自动生成+功能测试功能软件。本文简单介绍了在项目中集成swagger的方法和一些常见问题。如果想深入分析项目源码，了解更多内容，见参考资料。Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

整合

pom.xml

        <!-- swagger api文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.6.1</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.6.1</version>
        </dependency>

SwaggerConfig.java

package com.cleanhome.service.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author Yan
 * @date 2019/6/10 13:58
 *
 * swaggerui配置文件
 */

@Configuration
@EnableSwagger2
public class SwaggerConfig {



    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cleanhome.service.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("XXXX")
                .description("XXXX")
                .termsOfServiceUrl("https://yanxin152133.github.io/")
                .contact("yan")
                .version("1.0")
                .build();
    }

}

使用

package com.cleanhome.service.controller;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.cleanhome.service.bean.EjCustomer;
import com.cleanhome.service.service.impl.IEjCustomerServiceImpl;
import com.cleanhome.service.utils.Message;
import com.cleanhome.service.utils.MessageUtil;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.propertyeditors.CustomDateEditor;
import org.springframework.web.bind.WebDataBinder;
import org.springframework.web.bind.annotation.*;
import org.springframework.web.context.request.WebRequest;

import java.text.DateFormat;
import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.List;
import java.util.Map;

/**
 * @author Yan、ysq
 * @date 2019/6/11 8:40
 * 顾客
 * 主要功能：
 * 1.查询顾客的所有信息
 * 2.查询顾客数量
 * 3.添加顾客信息
 * 4.根据编号进行删除顾客信息
 * 5.根据编号进行更新操作
 */
@RestController
@RequestMapping("/customer")
@Api(value = "/customer", description = "顾客信息管理")
public class EjCustomerController {
    Logger logger = LoggerFactory.getLogger(EjCustomerController.class);

    @Autowired
    private IEjCustomerServiceImpl ejCustomerService;


    @InitBinder
    public void initBinder(WebDataBinder binder, WebRequest request) {

        //转换日期
        DateFormat dateFormat = new SimpleDateFormat("yyyy-MM-dd");
        binder.registerCustomEditor(Date.class, new CustomDateEditor(dateFormat, true));// CustomDateEditor为自定义日期编辑器
    }


    //查询顾客的所有信息
    @ApiOperation(value = "查询顾客的所有信息")
    @GetMapping("findAll")
    public Message findAll() {
        List<EjCustomer> list = ejCustomerService.findAll();
        logger.info("查询顾客所有信息成功");
        return MessageUtil.success("查询顾客所有信息成功", list);
    }

    //查询顾客数量
    @ApiOperation(value = "查询顾客数量")
    @GetMapping("findCustomer_Num")
    public Message findCustomer_Num() {
        int num = ejCustomerService.findCustomer_Num();
        logger.info("查询顾客数量成功");
        return MessageUtil.success("查询顾客数量成功", num);
    }

    //查询当天新增顾客量
    @ApiOperation(value = "查询当天新增顾客量")
    @GetMapping("TodayCustomerNum")
    public Message TodayCustomerNum() {
        int num = ejCustomerService.TodayCustomerNum();
        logger.info("查询当天新增顾客量成功");
        return MessageUtil.success("查询当天新增顾客量成功", num);
    }


    //添加顾客信息
    @ApiOperation(value = "添加顾客信息")
    @PostMapping("insert")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "顾客编号", required = false, dataType = "Integer"),
            @ApiImplicitParam(paramType = "query", name = "account", value = "顾客账号", required = true, dataType = "Long"),
            @ApiImplicitParam(paramType = "query", name = "password", value = "顾客账号密码", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "realname", value = "顾客真实姓名", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "status", value = "状态", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "photo", value = "顾客头像", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "telephone", value = "顾客联系方式", required = true, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "register_time", value = "顾客注册时间", required = true, dataType = "java.util.Date")
    })
    public Message insert(EjCustomer ejCustomer) throws Exception {
        boolean isValid = ejCustomerService.isExits(ejCustomer.getAccount());
        if (isValid) {
            try {
                ejCustomerService.insert(ejCustomer);
                logger.info("添加顾客信息成功");
                return MessageUtil.success("添加顾客信息成功");
            } catch (Exception e) {
                e.printStackTrace();
                return MessageUtil.error(e.getMessage());
            }
        } else {
            logger.warn("添加顾客信息失败");
            return MessageUtil.error("error");
        }
    }


    //根据顾客id删除用户信息
    @ApiOperation(value = "根据顾客id删除顾客信息")
    @GetMapping("deleteById")
    @ApiImplicitParam(paramType = "query", name = "id", value = "顾客编号", required = true, dataType = "Integer")
    public Message deleteById(Integer id) throws Exception {
        try {
            ejCustomerService.deleteById(id);
            logger.info("顾客编号为" + id + "删除成功");
            return MessageUtil.success("删除顾客信息成功");
        } catch (Exception e) {
            e.printStackTrace();
            logger.warn("顾客信息删除失败");
            return MessageUtil.error(e.getMessage());
        }
    }

    //根据顾客id进行更新操作
    @ApiOperation(value = "根据顾客id进行更新")
    @PostMapping("updateById")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "id", value = "顾客编号", required = true, dataType = "Integer"),
            @ApiImplicitParam(paramType = "query", name = "account", value = "顾客账号", required = false, dataType = "Long"),
            @ApiImplicitParam(paramType = "query", name = "password", value = "顾客账号密码", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "realname", value = "顾客真实姓名", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "status", value = "状态", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "photo", value = "顾客头像", required = false, dataType = "String"),
            @ApiImplicitParam(paramType = "query", name = "telephone", value = "顾客联系方式", required = false, dataType = "String"),
    })
    public Message updateById(EjCustomer ejCustomer) throws Exception{
        try {
            ejCustomerService.updateById(ejCustomer);
            logger.info("顾客编号"+ejCustomer.getId()+"更新成功");
            return MessageUtil.success("更新顾客信息成功");
        }catch (Exception e){
            e.printStackTrace();
            logger.warn("顾客信息更新失败");
            return MessageUtil.error(e.getMessage());
        }
    }


}

整合Swagger

2019-07-13
Spring Boot
Swagger

整合Swagger

整合

pom.xml

SwaggerConfig.java

使用